home *** CD-ROM | disk | FTP | other *** search
/ TeX 1995 July / TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO / web / schemeweb / README < prev    next >
Text File  |  1994-07-25  |  5KB  |  124 lines
  1. $Id: README,v 2.1 94/07/22 07:00:10 ramsdell Exp $
  2.  
  3. SchemeWEB---Simple support for literate programming in Lisp.
  4.  
  5. SchemeWEB is a Unix filter that allows you to generate both Lisp and
  6. LaTeX code from one source file.  The generated LaTeX code formats
  7. Lisp programs in typewriter font obeying the spacing in the source
  8. file.  Comments can include arbitrary LaTeX commands.  SchemeWEB was
  9. originally developed for the Scheme dialect of Lisp, but it can easily
  10. be used with most other dialects.
  11.  
  12. Version 2.1 implements several improvements over the version 1.2 which
  13. was released in 1990.
  14.  
  15. * The LaTeX source generated from a SchemeWEB file no longer requires
  16. the use of a style option, such as the astyped option required by the
  17. previous version.  The output is similar to that produced by c2latex.
  18.  
  19. * By default, Lisp source generated from a SchemeWEB file includes all
  20. comments.  As a result, the filter can translate the Lisp source
  21. generated from a SchemeWEB file directly into LaTeX source.
  22.  
  23. * The filter can translate the Lisp source generated from a SchemeWEB
  24. file into the original SchemeWEB file.
  25.  
  26. As a result of these changes, a SchemeWEB file can be stored and
  27. distributed as a standard Lisp file by tangling the SchemeWEB file.
  28. For the purposes of editing comments, the SchemeWEB file can be
  29. recovered by untangling the Lisp file.  LaTeX documentation can be
  30. generated from both the Lisp file or the SchemeWEB file.
  31.  
  32. Version 2.1 patches version 2.0 so it now correctly formats strings
  33. which span more than one line of text.
  34.  
  35. Installation:
  36.  
  37. 1) Create the executable by typing:
  38.  
  39.     make
  40.  
  41. 2) Install the executable and the manual page by typing:
  42.  
  43.     make install
  44.  
  45. By default the makefile will install the executable in $(prefix)/bin
  46. and the manual page in $(prefix)/man/man1, where prefix=/usr/local.
  47. You can change the prefix by typing:
  48.  
  49.     make prefix=<Your path> install
  50.  
  51. You can also change the installation targets by editing the makefile.
  52.  
  53. 3) You can modify the reader used by your Lisp system's standard LOAD
  54. so that it can read SchemeWEB files directly.  To make this change,
  55. follow the model given in "reader.sw", a reader of SchemeWEB source
  56. for the R4RS dialect of Scheme.
  57.  
  58. A formatted version of the manual page follows.
  59.  
  60. -----------------------------------------------------------------
  61.  
  62. sweb(1)                  USER COMMANDS                    sweb(1)
  63.  
  64.  
  65.  
  66. NAME
  67.      sweb - Simple support for literate programming in Lisp.
  68.  
  69. SYNOPSIS
  70.      sweb [-stuvwx] [input_file [output_file]]
  71.  
  72. DESCRIPTION
  73.      A SchemeWEB file is a Lisp source file which  contains  code
  74.      sections  and  comment sections, but each section is identi-
  75.      fied in a novel way.  A code  section  begins  with  a  line
  76.      whose  first  character is a left parenthesis.  It continues
  77.      until a line is found which contains  the  parenthesis  that
  78.      matches the one which started the code section.  The remain-
  79.      ing lines of text in the source file  are  treated  as  com-
  80.      ments.
  81.  
  82.      Several operations involving SchemeWEB files are provided by
  83.      the sweb program.
  84.  
  85.      The -t option translates a SchemeWEB file  into  a  standard
  86.      Lisp  file.   It simply adds an initial semicolon to comment
  87.      lines that lack  them,  and  passes  code  sections  through
  88.      unchanged.   This  process  is called tangling the SchemeWEB
  89.      file.
  90.  
  91.      The -w option translates  a  SchemeWEB  file  into  a  LaTeX
  92.      source  file.   Text is added to code sections so that LaTeX
  93.      will print the code verbatim.  Comment sections  are  passed
  94.      through  unchanged  except  that if the first character of a
  95.      line is a semicolon, it is excised.  This makes it  possible
  96.      to  process  a  SchemeWEB file which has been tangled.  This
  97.      process is called weaving the SchemeWEB file.  This  is  the
  98.      default action of sweb.
  99.  
  100.      The -x option weaves a SchemeWEB file as above,  except  the
  101.      LaTeX source produced inhibits page breaks in code sections.
  102.  
  103.      The -u option translates a Lisp file which has been produced
  104.      from a SchemeWEB file back into a SchemeWEB file.  It simply
  105.      removes the first semicolon in every line that  starts  with
  106.      one  as  its first character.  This process is called untan-
  107.      gling a sweb produced Lisp file.
  108.  
  109.      The -s option tangles a SchemeWEB file and strips  all  com-
  110.      ments from the file.
  111.  
  112.      The -v option prints version information.
  113.  
  114.      A SchemeWEB file can be stored and distributed as a standard
  115.      Lisp  file by tangling the SchemeWEB file.  For the purposes
  116.      of editing comments, the SchemeWEB file can be recovered  by
  117.      untangling  the  Lisp  file.   LaTeX  documentation  can  be
  118.      generated from both the Lisp file or the SchemeWEB file.
  119.  
  120.      SchemeWEB was originally developed for the Scheme dialect of
  121.      Lisp;  however,  it  became  obvious  that  no  changes were
  122.      required to support most other dialects.   SchemeWEB's  name
  123.      reflects its heritage.
  124.